MacWorld 1997 September/Macworld (1997-09).dmg/Shareware World/Utilities/Text Processing/Alpha/LaTeX/latex 2.09/LaTeX Help

Text File | 1996-07-01 | 27KB | 487 lines

I.  OVERVIEW

This is the 'LaTeX Help' file available from Alpha's Help menu.
Besides this help file, there is also the file ``LaTeX Key Bindings''
on the Help menu, which contains an alphabetical listing of all the
command keys bound to the various \LaTeX\ commands.  In addition to
these on-line help files, there are other documentation files stored
in \Alpha's \LaTeX\ folder called 'latex_commands.tex' and
'latex_keys.tex' in the LaTeX 2.09 folder.  These files contain
numerous tables summarizing the commands on the \LaTeX\ menu and their
key bindings, and can be viewed or printed with your favorite \LaTeX\
application.

The LaTeX Menu
--------------

Upon entering TeX mode, either manually (by choosing Modes:Tex from the
Misc menu or via the pop-up menu to the left of the window's horizontal
scroll bar) or automatically (whenever a .tex or .sty file is activated), a
new menu appears in the menu bar. The LaTeX menu provides access to scores
of procedures stored in source form in the file latex.tcl and loaded the
first time 'Tex' mode is entered. The LaTeX menu follows closely the
organization and terminology of L. Lamport's _LaTeX_ book (Addison-Wesley,
1986), especially chapter 3. It's generally agree that the _LaTeX_ book is
still the definitive LaTeX reference and should be on every LaTeX user's
desk.

Basic Operations
----------------

The macros in latex.tcl revolve around two basic operations called
insertObject and wrapObject. Basically, the insertObject operation is a
call to insertText preceded by the automatic deletion of previously
selected text (this is easily changed, however, by resetting the flag
'deleteObjectNoisily' on the Utils menu). For example, if there is no
current selection, choosing the command Greek:Alpha from the LaTeX menu
inserts the corresponding LaTeX command at the insertion point; otherwise
it replaces the current selection with the string "\alpha". In other words,
insertObject works just like the familiar Edit:Paste command. A good
portion of the commands in latex.tcl rely on insertObject but actually
these are least important since it's almost always easier to type them at
the keyboard. On the other hand, if we forget the syntax of a particular
LaTeX command, it's quicker to look it up on the menu than it is in the
_LaTeX_ book. Additional time savings may be realized when these commands
are used in conjunction with their corresponding command keys...but more on
that later.

The operation complementary to insertObject is called wrapObject. The
difference between the two is the way the latter treats the current
selection. That is, wrapObject inserts its argument at the insertion point
(just like insertObject), but if there is a selection, wrapObject cuts it
out (without effecting the current state of the Clipboard) and inserts it
in the middle of the chosen command. For example, consider the LaTeX menu
command Miscellaneous:Footnote. This command inserts the string
"\footnote{}•" (minus the double quotes, of course) into the document,
positioning the insertion point between the pair of braces. The user then
types the text to be footnoted and presses the Tab key, after which the tab
stop macro finds the bullet • at the end of the string. (Note: use
option-tab or control-tab to insert a literal tab character into the
document.) On the other hand, if a selection exists at the time
LaTeX:Miscellaneous:Footnote is issued, the selection itself is surrounded
by LaTeX's \footnote command, and the insertion point is brought to the end
of the selection automatically. Some commands, for better or worse, even go
so far as to insert the selection into one of several competing positions
within the command string. The LaTeX:Formulas:Fraction command is a good
example of this type of behavior. It assumes the current selection (if
there is one) is the numerator of the fraction to be typeset, cutting &
pasting accordingly.

The concept of wrapping an object is carried one step further in the case
of environments. Suppose you want to center an existing tabular
environment, for example. Just select the tabular environment and then
choose Environments:General from the LaTeX menu. A dialog will appear
prompting the user for the name of the environment. Since "center" is the
default, just press the OK button in the dialog box. The resulting
centering environment will completely surround the existing tabular
environment, indenting the latter one tab stop to the right.

Not all environments wrap, however. Those environments whose body is very
structured (that is, enumerate, itemize, description, tabular,
thebibliography, array, eqnarray, and eqnarray*) do not. Instead, these
environments simply insert text into the document. If there happens to be a
selection at the time one of these commands is issued, an alert appears
asking if the selection should be deleted. To turn this alert off, simply
toggle the flag 'deleteEnvironmentNoisily' on the Utils menu.

Whitespace
----------

Before going on, let me say a few words about whitespace. In virtually all
cases, superfluous whitespace in command strings has been deleted. For
example, objects inserted with insertObject (a sizable portion of
latex.tcl's functionality) do not routinely insert a trailing space
character. Instead, the user must decide whether or not space should
immediately follow a particular TeX or LaTeX control word (sometimes it's
needed, and sometimes it's not). Setting indentOnCR to false also prevents
a lot of extraneous whitespace from being inserted into your document (but
then it won't look so good!)


II.  VERSION HISTORY

Changes in Version 2.0
----------------------

 • The documentation (LaTeX Help and commands.tex) has been totally
   rewritten.
 • A new, expanded LaTeX menu has been implemented, following closely the
   organization and terminology of the LaTeX book.
 • Ellipses have been added to LaTeX menu items where appropriate.
 • Macros intelligently respond to the current selection---although
   many objects simply replace the current selection (similar to Paste),
   others conveniently and automatically wrap themselves around it.
   Environments automatically wrap themselves around a selection, too.
 • Functionality has been localized in utility macros as much as possible.
 • Standard document types (letter, article, report, and book) have been
   added.  Simply select some text (or not) before choosing the desired
   command from the Documents menu.
 • Three flags have been added to the Utils menu:  'useBoxMacro' (which
   controls the behavior of the figure environment), 'deleteObjectNoisily'
   (which controls an alert that appears when the current selection is
   about to be replaced by an object), and 'deleteEnvironmentNoisily'
   (which controls an alert that appears when the current selection is
   about to be replaced by an environment).
 • Many new environments have been added (figure, table, verbatim, quote,
   quotation, verse) and some (enumerate, itemize, description, tabular,
   bibliography, array, eqnarray, and eqnarry*) now prompt the user for
   the desired number of rows and, in some cases, columns.  The environment
   body is then constructed automatically.
 • The figure environment now depends on a flag called 'useBoxMacro' on the
   Utils menu.  If this flag is true (which it is by default), then the
   figure environment inserts the string "\\centerline{\\$boxMacroName{•}}"
   into its body.  Otherwise, the body of the figure environment is left
   empty (unless there is a current selection, in which case the figure
   environment wraps).
 • A new, improved fraction macro now parses a selection of the form
   "numerator/denominator" and then automatically constructs the
   corresponding displayed fraction.  A selection not containing a
   "/" is inserted in lieu of the fraction's numerator.
 • Both TeX and LaTeX math modes are supported, including $...$, $$...$$,
   \(...\), and \[...\].  These are inserted into the document horizontal-
   ly.  The corresponding multi-line environments \begin{math}...\end{math}
   and \begin{displaymath}...\end{displaymath} are also supported and
   heartily recommended (since these constructs are more easily modified
   and maintained by the user).
 • There's now a two-parameter nth root, in addition to square root.
 • Arbitrary one- and two-parameter LaTeX commands have been implemented,
   namely, \<command>{•} and \<command>{•}{•}.  These can be run inter-
   actively, or used as templates for user-defined commands.
 • In addition to sum and integral, numerous "large operators" (product,
   union, intersection, logical and/or) have been added.
 • The nonumber command has been removed since it only appears in the
   context of an eqnarray environment.
 • Both the Conjugate and Expected Value commands have been removed since
   in my (perhaps limited) experience these are nonstandard mathematical
   notation.
 • Sectioning commands no longer insert a trailing carriage return.
 • The Sum and Integral commands no longer typeset the current selection
   as the lower limit of the sum or integral.
 • The command texDisplayEqn is no longer supported. Instead, the commands
   MathModes:texDisplaymath and MathModes:latexDisplaymath insert
   themselves horizontally into the .tex file.  For vertical source code
   formatting, use MathEnvironments:Displaymath.
 • Extraneous comments preceding each environment have been removed.
 • The command alignEqual has been removed since the separator is now
   inserted automatically into the appropriate environments.

Changes in Version 1.2
----------------------

 • **IMPORTANT**: KEYBINDINGS NOW DEPENDENT ON optionIsMeta FLAG

 • macros shortened through use of movePoint and selReplace utility macros.
 • new macros added: section, subsection, subsubsection, enumerate,
   itemize
 • most short macros handle selected text (i.e. highlight "word", execute
   the boldface command, and you get "{\bf word}").  NOTE: this is
   OPTIONAL--you can still execute boldface, type "word", and type tab.
 • latex key bindings only performed the first time Tex mode is entered,
   to save time
 • emphasize macro updated

Changes in Version 1.1
----------------------

 • non-breaking space removed from cite macro
 • slide environment macro added and assigned to o-F9 and c-o-9
 • equation, displaymath, eqnarray, eqnarray*, slide, and general environment
   now indent and no longer insert a blank line if called from column 0.
 • texDisplayEqn ($$...$$) added and bound to o-s-4

Known Bugs
----------

 • the figure and table environments need an optional LaTeX parameter
 • the italic correction is not very smart, especially when wrapping
   an object
 • the fraction command does not remove redundant parentheses
 • the Alpha variable 'indentOnCR' should reduce extraneous whitespace
   to near zero when set to false
 • the mathStyle:calligraphic command should check to see that its
   argument is upper-case
 • the various commands on the Documents submenu should make sure the
   file is empty (if inserting) or totally selected (if wrapping)

In the Works
------------

 • an interactive list-making command
 • interactive (re)newcommand, (re)newenvironment, and newtheorem commands
 • international characters
 • a tabbing environment (yuck!)
 • an index environment
 • additional TeX and LaTeX boxes
 • log-like functions
 • multi-line delimiters
 • a less obtrusive and more general tab-stopping mechanism
 • support for the AMS math fonts
 • the ability to "unwrap" fractions and other complex objects


III.  MENUS

The LaTeX menu is organized into three parts: document-related commands,
paragraph mode commands (that is, normal text commands), and math mode
commands. Each group of commands is separated by a thin grey line on the
menu. A brief description of the available commands follows. See the file
'commands.tex' for more specific information.

Document-related Commands
-------------------------

In addition to the standard LaTeX document styles (letter, article, report,
and book) a custom document style that runs interactively is available.
Choosing one of these commands from the Documents submenu either inserts
the desired template at the insertion point or, if there is a current
selection---say, a paragraph of text or even a whole document---the
selection is wrapped up inside the chosen document style. In either case,
the insertion point is positioned at the beginning of the template allowing
the user to enter any specific document-style options that may be required
(standard options include 11pt, twoside, and twocolumn, for example).
If none are desired, simply skip over this part of the template (it's okay
to leave the empty square brackets where they are).

Numerous LaTeX sectioning commands are available from the Sectioning
submenu, the most useful being the chapter, section, and subsection
commands. The corresponding LaTeX command is inserted at the insertion
point. The current selection, if there is one, is assumed to be the name of
the section and is wrapped up inside curly braces. The resulting
declaration is NOT followed by a carriage return since the user has the
option of putting a label (or whatever) on the same line.

Future versions of latex.tcl will provide tools for constructing various
command and environment definitions.

Paragraph Mode Commands
-----------------------

Taken together, the Text Style and Text Size submenus contain most of
LaTeX's text formatting declarations. Since I usually override LaTeX's
default settings only for very small amounts of text (typically a sentence
or less), the scope of each of these declarations has been delimited by
braces even though there may be times when this approach is superfluous and
even outright wrong. (This "feature" may change in future versions of
latex.tcl.)

I should also say something about TeX's italic correction which forced
some difficult design choices. Paraphrasing Shakespeare, "To correct, or
not to correct, that is the question!" The compromise (which I hope doesn't
turn out to be a mistake) was to consistently include the italic correction
"\/" with each instance of Italic, Emphatic (preferred in the vast majority
of cases) or Slanted text, but then to highlight the correction so the user
could choose to delete it easily. So, immediately after inserting one these
three declarations, decide which way to go by pressing the delete key or
not.

Future versions of latex.tcl will implement TeX's extensive international
character set and diacritical marks.

Perhaps the most useful of latex.tcl's many features is its ability to
produce skeletal templates for multi-line environments (that is, LaTeX
constructs delimited by a \begin...\end pair). These may be inserted
anywhere in the document (even in the middle of a line), complete with tab
stops and appropriate indentation (provided the Alpha variable indentOnCR,
available on the Utils menu, is set to true). On the Environment submenu,
you'll find commands for Enumerate, Itemize, Description, Tabular, Figure,
Table, Slide, Verbatim, Quote, Quotation, Verse, and Bibliography
environments. In some cases (like Enumerate), the user is asked to specify
the number of rows desired, after which the program generates the
corresponding environment body (complete with punctuation and tab stops).
Some environment commands (like Tabular) also prompt the user for the
desired number of columns. There's even a General command for creating
user-defined environments.

Although the Boxes submenu is unusually brief, I expect this to change as I
learn more about TeX boxes. Perhaps the most useful box-making command (the
only one implemented thus far) is mbox, which formats its argument in LR
mode, a restricted form of paragraph mode impervious to line breaks. The
mbox command is especially useful for inserting a bit of plain text in the
middle of a math formula (see the _LaTeX_ book for examples).

Other text-related LaTeX commands that I've found useful from time to time
are listed under the Miscellaneous submenu. There you'll find certain
special characters (like Copyright and Section Mark), the TeX and LaTeX
logos, quoting commands (which I've always found difficult to typeset
manually), marginal notes and footnotes, labels, cross references, page
references, and citations.

Math Mode Commands
------------------

Math mode may be invoked in any number of ways. Many TeXnical typists rely
exclusively on TeX's use of dollar signs, and almost always key in their
documents horizontally from left to right. Others have adopted LaTeX's
tendency to prefer vertical constructions (that is, environments). Still
others have settled on some combination of these, using whichever seems
comfortable or convenient at the time. Whatever your approach to
mathematical typesetting, there's something for everybody in latex.tcl,
designed to simplify the input of complex mathematical formulas.

Four Math Modes are available for normal, everyday left-to-right input.
These are called Tex Math ($...$) and Tex Displaymath ($$...$$), and their
corresponding LaTeX equivalents Latex Math (\(...\) and Latex Displaymath
\[...\]. The LaTeX versions are equivalent to the multi-line Math and
Displaymath environments. The latter have the advantage that 1) they are
often more readable in source form, and 2) they are more easily changed (by
simply replacing keywords) as the document evolves.

Other multi-line Math Environments peculiar to LaTeX (Equation, Array,
Eqnarray, and Eqnarray*) are also available, and each is mutually exclusive
(that is, one may not be nested inside the other) except for the Array
environment which _must_ be nested inside some other math environment. (It
took me a long time to come to grips with this anomaly, and I must say the
misleading example on p.47 of the _LaTeX_ book sure didn't help!) There's
also a General environment command which turns out to be exactly the same
one available in paragraph mode (see above).

The Formulas submenu contains LaTeX commands commonly used to build up even
the simplest mathematical expressions. There are commands for typesetting
subscripts and superscripts, fractions (which used to be difficult to
typeset), square roots, and arbitrary nth roots. There are also arbitrary
one- and two-parameter LaTeX commands which prompt the user to input the
command name. Next to latex.tcl's environment commands, the formula
commands should be most useful. (In fact, it pays to memorize their command
key equivalents...but more on that later.)

While we're talking about the Formulas submenu, let me tell a little bit
about latex.tcl's ability to parse fractions. How many times have you found
yourself wanting to recast a horizontally typeset fraction such as $x = (-b
\pm \sqrt{b^2 - 4ac})/(2a)$ in a corresponding "vertical" form such as $$x
= \frac{(-b \pm \sqrt{b^2 - 4ac})}{(2a)}$? Obviously, such an operation
involves a lot of cutting and pasting, and I used to avoid it like the
plague. Well, now all you have to do is select the text you want converted
(in this case, all the text inside the dollar signs except "x = ") and then
choose Formulas:Fraction from the LaTeX menu. The rest is automatic. (Now
if only I could get it to automatically remove those redundant
parentheses... :-)

The longest of latex.tcl's submenus contains the entire Greek alphabet,
including both lower- and upper-case letters, plus a handful of lower-case,
"italicized" letters (\varepsilon, \vartheta, \varpi, \varrho, \varsigma,
and \varphi). The upper-case letters have been prefixed with the keyword
"Cap" on the Greek submenu since the words "theta" and "Theta," for
instance, are indistinguishable to Alpha's menu processor.

Plain TeX defines an incredible variety of mathematical symbols, each
transparently available to the LaTeX user, but only a fraction of these
have been implemented in this version of latex.tcl. The Binary Operators
and Relations submenus contain a couple dozen of the most commonly used
symbols, although others may be added quite easily (it'll be difficult to
find appropriate command keys, however!). The latex.tcl macro package also
provides support for TeX's so-called "large operators." Commands such as
Sum, Product, Integral, set Union and Intersection, and Logical And and Or
may be found on the Large Operators submenu.

Similarly, a quick glance at the _LaTeX_ book shows a wide assortment of
arrows, dots, and miscellaneous mathematical symbols---only some of which
are implemented in latex.tcl. See the Arrows, Dots, and Symbols submenus
for lists of available commands.

TeX's so-called "log-like" functions (\exp and \sin, for instance) are
scheduled to be implemented in future versions of latex.tcl. (Quite
frankly, I find it easier to type these commands directly as opposed to
pulling down a menu, but I admit they might be useful in some instances.)

TeX is particularly adept at "delimiting" arbitrary-sized mathematical
expressions. Examples include parenthesized equations, matrices, and
determinants. Since the left and right delimiters need not be of the same
type, there are a host of options from which to choose, and hence we're
presented with an interesting design problem. A workable compromise was
achieved by implementing a handful of common delimiters explicitly, and
then providing access to other more esoteric combinations via dialogs.
Consequently, commands for Big Parentheses, Big Brackets, Big Braces, and
Big Absolute Value symbols will be found on the Delimiters submenu, along
with a Big Left Brace (which is commonly used to define multi-part
functions or systems of equations), as well as interactive commands called
Other Big Delims and Other Mixed Big Delims. The latter two commands are
interactive---the user either types the delimiter name directly into a text
box or chooses the desired name from a pop-up menu of available options.
Also on the Delimiters submenu are normal-sized parentheses, brackets,
braces, and absolute values, as well as arbitrary fixed-size delimiters.

Math accents (not to be confused with diacritical marks used in paragraph
mode) are accessed from a submenu of the same name. There are commands for
hats, bars, tildes, vectors, dots, etc., plus wide hats and tildes. There
are also commands for dotless versions of the letters "i" and "j" used in
conjuction with these accents. Insofar as possible, the macros check to
make sure that only single characters are being accented, or in the case of
wide accents, three or fewer characters.

The Grouping submenu has commands for underlining and overlining, and
related commands for creating underbraces and overbraces. There's also a
command for something called a stack used to construct compound operators
via vertical stacking (see p.52 of the _LaTeX_ book for more details).

The Spacing submenu provides for various types of horizontal spacing. There
are commands for thin, negative thin, medium, and thick amounts of
whitespace, and additional commands for inserting the traditional
typesetter's quad (1em) and double quad. Arbitrary horizontal whitespace,
defined via LaTeX's \hspace and \hspace* commands, may be inserted with the
One Parameter command on the Formulas menu. Vertical whitespace commands
have not yet been implemented.

The last submenu on the LaTeX menu is called Math Style, with commands for
(the seldom used) Math Italic and Calligraphic typefaces, as well as
declarations for displaystyle, textstyle, scriptstyle, and
scriptscriptstyle. The latter command quartet are sometimes needed to
override LaTeX's default math style. (For example, the array environment
for some bizarre reason insists on enabling textstyle regardless of the
surrounding environment.) Future versions of latex.tcl will also provide
support for the AMS Fonts, including Fraktur, Script, and Blackboard Bold.


IV.  COMMAND KEYS

Menus are great when first learning a program, but eventually the tendency
is to move away from menus towards commands keys. This can significantly
speed input. However, few of us are inclined to memorize more than a couple
dozen such keystrokes unless continually prompted with reminders.
Unfortunately, it's not possible to display complex command key icons on Alpha
menus and so we must resort to external aids (see the file commands.tex in
the Help folder). Other than that, a logical approach to key assignments is
about all we can hope for.

Key Assignments
---------------

A few remarks will help you remember the many command key sequences. Almost
all commands that use wrapObject have been assigned command keys beginning
with <Cmd Shf> or <Cmd Opt> or <Cmd Shf Opt>. The first of these is
reserved for paragraph mode and the others for math mode. On the other
hand, commands that use insertObject almost always have command keys
beginning with <Opt> or <Opt Shf> or <Opt Ctl>. Knowing these simple facts
will help tremendously.

In may cases, we've honored normal Mac keyboarding conventions. Thus,
Bullet and Ellipsis have been assigned <Opt 8> and <Opt ;>, respectively.
Similarly, the commands Less Or Equal and Greater Or Equal have been
assigned <Opt ,> and <Opt .>, respectively. There are others that you'll
no doubt recognize, too.

There's also a certain amount of redundancy built in.  For example, the
ubiquitous Subscript and Superscript commands each have a pair of command
keys assigned to them, <Cmd Opt ,> and <Cmd Opt -> in the case of Subscript,
and <Cmd Opt .> and <Cmd Opt 6> for Superscript. Take your pick!

Meta Keys
---------

The LaTeX key bindings make heavy use of the option key.  This is fine
if you never learned those strange emacs-type key combinations, or if
you are accustomed to using the escape key for the meta-key combinations.
However, if you are taking advantage of Alpha's ability to use the option
key for the meta-key combinations (by setting optionIsMeta to 1), you
have undoubtedly noticed that you have a problem in Tex mode, where
option-v inserts "\nabla" rather than scrolling up one screen.

Fear not. If you want to use option as a meta key in Tex mode, open the
procs.tcl file, use the Mark titlebar menu to find the mark
"latexMacroOption", type a pound sign "#" (without the quotes), save the
file, and quit Alpha. (If the mark is missing from procs.tcl, look for the
"setTexMode" procedure and read the comments.) When you restart Alpha and
enter Tex mode, the optionIsMeta flag will have been left set, the latex
key bindings will all have the control key added to them (except the tab
key), and option will work as a meta key.